---
title: Migrating from Pyright

description: How to switch your type checker configuration from Pyright to Pyrefly
---

## Running Pyrefly

Like pyright, pyrefly can be given a list of files to check:

```sh
$ pyrefly check file1.py file2.py
```

The easiest way to run pyrefly on all files in a project is to run it from the project root:

```sh
$ cd your/project
$ pyrefly check
```

Pyrefly doesn't need a config file to start checking your code. Its sensible defaults are designed to work well for most projects.
However, projects with existing pyright configs may want to configure pyrefly to suit their own needs.

## Pyright Config Migration

To make it as easy as possible to get started with pyrefly, we've provided a script for automatically migrating a pyright config to pyrefly.

```sh
$ pyrefly init path/to/your/project
```

This will search for an existing `pyrightconfig.json` or `pyproject.toml` with a `tool.pyright` section, and then transform it into a `pyrefly.toml` (or `[tool.pyrefly]` section) while preserving as many options as possible. See `init --help` for more options.

There is a significant overlap between pyright's and pyrefly's configuration options, so migration is pretty straightforward. However, it may be worth checking the generated config for errors, just in case.

If you'd rather start fresh with a hand-written config, please see the [pyrefly configuration docs](configuration.mdx).
If you run into any issues with config migration, please [let us know](https://github.com/facebook/pyrefly/issues)!

## Config Migration Details

When it comes to listing files, pyright uses just paths, while pyrefly supports glob patterns. Thankfully, paths are a subset of glob patterns, so pyrefly can just use the paths as-is. You could consider manually simplifying the paths into glob patterns, but it's not necessary.

Pyright supports four platforms: Windows, Linux, Darwin (macOS), and All. Since pyrefly only supports Python's [supported platforms](https://docs.python.org/3/library/sys.html#sys.platform), we choose to treat "All" as "linux".

### Type Check Diagnostic Settings and Error Kinds

Pyrefly maps pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings) to equivalent pyrefly [error kinds](error-kinds.mdx).
While not every diagnostic setting has an equivalent error kind, we make an effort to ensure that pyrefly suppresses the same errors that pyright does.

This may lead to overly broad error suppressions, and you may want to consider removing some error kinds from the disable list.
You can also use a [SubConfig](configuration.mdx#sub_config) to selectively silence errors in specific files,
or see [Silencing Errors](#silencing-errors) for how to suppress errors at the source.

See [Error Kind Mapping](#error-kind-mapping) for a table showing the relationship between type check diagnostic settings and error kinds.

### Execution Environments

Pyright's [execution environments](https://microsoft.github.io/pyright/#/configuration?id=execution-environment-options) let you customize the Python version, platform, module search paths, and diagnostic settings for some part of your project.
Pyrefly's [SubConfigs](configuration.mdx#sub_config) are a similar mechanism that let you configure pyrefly's behavior for files matching a filepath glob.
However, subconfigs do not support changing the Python version, platform, or module search paths.

Diagnostic settings are carried over to the equivalent subconfig, using the mapping mentioned [above](#type-check-diagnostic-settings-and-error-kinds).

### Extending Builtins

Pyright automatically imports any builtins defined in `__builtins__.pyi` at the project root or in a custom stubs directory specified by `stubPath` (defaulting to `./typings`).

Pyrefly supports this behavior - the directory for `stubPath` should be added to your Pyrefly config's `site-package-path`.

## Silencing Errors

Like pyright, pyrefly has ways to silence specific error codes. Full details can be found in the [Error Suppression docs](error-suppressions.mdx).

To silence an error on a specific line, add a disable comment above that line. You can either suppress all errors on that line:

```
# pyrefly: ignore
x: str = 1
```

Or target a specific error type:

```
# pyrefly: ignore[bad-assignment]
x: str = 1
```

To suppress all instances of an error, disable that error in the config:

```
[errors]
missing-import = false
```

This is similar to pyright's [type check rule overrides](https://microsoft.github.io/pyright/#/configuration?id=type-check-rule-overrides), though of course the [error codes](error-kinds.mdx) are different!

You can also use:

```toml
permissive-ignores = true
```

To allow `pyright: ignore` comments to be used by Pyrefly.

## Error Kind Mapping

This table shows the mapping between pyright's [type check diagnostics settings](https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings)
and pyrefly's [error kinds](error-kinds.mdx).

This table will be expanded as more diagnostics are supported.

| Pyright | Pyrefly |
| ------- | ------- |
| reportMissingImports | missing-import |
| reportMissingModuleSource | missing-import |
